NAZWA¶

glob, globfree - znalezienie ścieżek odpowiadających wzorcowi, zwolnienie pamięć z glob()

SKŁADNIA¶

#include <glob.h>

int glob(const char *pattern, int flags,
         int errfunc(const char *epath, int eerrno),
         glob_t *pglob);
void globfree(glob_t *pglob);

OPIS¶

Funkcja glob() przeszukuje wszystkie ścieżki odpowiadające wzorcowi pattern, stosując przy tym reguły takie, jakich użyłaby powłoka (zobacz glob(7)). Nie jest dokonywane rozwinięcie tyldy ani podstawienie parametrów. Jeśli są one potrzebne, to należy użyć wordexp(3).

Funkcja globfree() zwalnia obszar pamięci zaalokowany dynamicznie przez wcześniejsze wywołanie funkcji glob().

W wyniku wywołania glob() tworzona jest struktura, na którą wskazuje pglob, będący typu glob_t zadeklarowanego w <glob.h> i zawierającego następujące elementy zdefiniowane przez POSIX.2 (mogą też występować dodatkowe, ale jako rozszerzenie):

typedef struct
{




    size_t gl_pathc;    /* Liczba odpowiadających dotąd ścieżek  */


    char **gl_pathv;    /* Lista odpowiadających ścieżek.  */


    size_t gl_offs;     /* Sloty do rezerwowania w `gl_pathv'.  */


} glob_t;

Wyniki są zachowywane w dynamicznie przydzielanym obszarze pamięci.

Parametr flags tworzy bitowe OR zera lub więcej następujących symboli stałych modyfikujących zachowanie glob():

GLOB_ERR

oznacza, że należy powrócić po błędzie odczytu (np. gdy katalog nie ma praw odczytu),

GLOB_MARK

oznacza dodawanie ukośnika do każdej ścieżki, która odpowiada katalogowi,

GLOB_NOSORT

oznacza, że zwracane ścieżki nie mają być sortowane (domyślnie są),

GLOB_DOOFFS

oznacza, że sloty pglob->gl_offs będą rezerwowane na początku listy napisów w pglob->pathv,

GLOB_NOCHECK

oznacza, że jeśli żaden wzorzec nie odpowiada, zwracany jest wzorzec oryginalny,

GLOB_APPEND

oznacza, że należy doklejać wyniki do wyników poprzedniego wywołania. Nie należy ustawiać tej flagi przy pierwszym wywołaniu glob().

GLOB_NOESCAPE

oznacza, że metaznaki nie mogą być cytowane odwrotnymi ukośnikami,

Parametr flags może również zawierać następujące znaczniki, będące rozszerzeniami GNU nie definiowanymi przez POSIX.2:

GLOB_PERIOD

oznacza, że początkowa kropka może być dopasowana metaznakiem,

GLOB_ALTDIRFUNC oznacza, że przy dostępie do systemy plików zamiast zwykłych funkcji bibliotecznych używane są funkcje alternatywne pglob->gl_closedir, pglob->gl_readdir, pglob->gl_opendir, pglob->gl_lstati pglob->gl_stat,

GLOB_BRACE

oznacza, że rozwijane są wyrażenia nawiasowe {a,b} w stylu csh(1),

GLOB_NOMAGIC

oznacza, że wzorzec jest zwracany, gdy nie zawiera metaznaków,

GLOB_TILDE

oznacza, że przeprowadzane rozwinięcie tyldy, a

GLOB_ONLYDIR

oznacza, że dopasowywane są wyłącznie katalogi.

Jeśli errfunc nie jest równe NULL, to w wypadku błędu będzie ono wywołane z argumentami epath, czyli wskaźnikiem do ścieżki, na której coś się nie powiodło i z eerrno, przechowującym wartość errno, zwróconą przez wywołanie do opendir(), readdir() lub stat(). Jeśli errfunc zwraca wartość niezerową lub jeśli ustawiony jest znacznik GLOB_ERR, glob() zakończy działanie po wywołaniu funkcji errfunc.

Po pomyślnym zakończeniu, pglob->gl_pathc zawiera liczbę pasujących ścieżek, a pglob->gl_pathv wskaźnik do listy trafionych ścieżek. Pierwszy wskaźnik za ostatnią ścieżką ma wartość NULL.

Możliwe jest wywoływanie glob() wielokrotnie. W takim wypadku, należy w następnych wywołaniach ustawić w flags znacznik GLOB_APPEND.

Jako rozszerzenie GNU, pglob->gl_flags jest ustawiane jako or podanych znaczników i GLOB_MAGCHAR, gdy występują metaznaki.

WARTOŚĆ ZWRACANA¶

Po pomyślnym zakończeniu glob() zwraca zero. Inne możliwe wartości to:

GLOB_NOSPACE

przy braku pamięci,

GLOB_ABORTED

przy błędzie odczytu i

GLOB_NOMATCH

gdy niczego nie dopasowano.

PRZYKŁADY¶

Jednym z przykładów użycia jest następujący kod, emulujący wpisanie ls -l *.c ../*.c w powłoce.

glob_t globbuf;
globbuf.gl_offs = 2;
glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf);
globbuf.gl_pathv[0] = "ls";
globbuf.gl_pathv[1] = "-l";
execvp("ls", &globbuf.gl_pathv[0]);

ZGODNE Z¶

POSIX.2

BŁĘDY¶

Funkcja glob() może zawieść z powodu błędu wywołanych przez nią funkcji, takich jak malloc() czy opendir(). Wywołania te zapiszą kod błędu w errno.

UWAGI¶

Elementy gl_pathc i gl_offs struktury są w glibc 2.1 zadeklarowane jako size_t, jak powinno być zgodnie z POSIX.2, ale są zadeklarowane jako int w libc4, libc5 i glibc 2.0.

ZOBACZ TAKŻE¶

ls(1), sh(1), stat(2), exec(3), malloc(3), opendir(3), readdir(3), wordexp(3), glob(7)